docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap#969
Closed
danielmeppiel wants to merge 1 commit intomainfrom
Closed
docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap#969danielmeppiel wants to merge 1 commit intomainfrom
danielmeppiel wants to merge 1 commit intomainfrom
Conversation
…Hub-render trap
GitHub's mermaid parser rejects ':::cssClass' appended to a relationship
line ('A *-- B:::touched') with parse error 'Expecting NEWLINE, EOF,
LABEL, got STYLE_SEPARATOR'. The shorthand is only valid as a
standalone 'class Name:::cssClass' declaration in classDiagram. This
trap silently breaks rendered diagrams in panel review verdict comments,
which are the persona's authoritative output channel.
The persona's existing illustrative example was already correct; this
adds an explicit gotcha block so the rule cannot be missed. Trap does
not apply to flowchart diagrams, where the inline form is valid.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
Author
|
Closing -- redoing in a git worktree to avoid disturbing parallel local work. Will reopen. |
Contributor
There was a problem hiding this comment.
Pull request overview
Documents a GitHub Mermaid parsing gotcha in the Python Architect persona contract to prevent broken classDiagram rendering when using the :::cssClass shorthand.
Changes:
- Add an explicit gotcha note explaining that
:::cssClasscannot be appended toclassDiagramrelationship lines on GitHub. - Regenerate the
.github/mirror of the agent file from.apm/. - Update
apm.lock.yamlto reflect the new mirror file hash.
Show a summary per file
| File | Description |
|---|---|
.apm/agents/python-architect.agent.md |
Adds a Mermaid classDiagram GitHub-render gotcha note to the authored persona contract. |
.github/agents/python-architect.agent.md |
Regenerated mirror of the updated persona contract content. |
apm.lock.yaml |
Updates the content hash for the regenerated .github/agents/python-architect.agent.md. |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
While running the apm-review-panel skill on Epic #898, the Python Architect's "After" class diagram failed to render on GitHub with:
The cause: GitHub's mermaid parser only accepts the
:::cssClassshorthand as a standaloneclass Name:::cssClassdeclaration inclassDiagram. Appending it after a relationship arrow (A *-- B:::touched) parses fine in flowchart but not in classDiagram. The persona's existing example was already correct, but the rule was implicit -- the next reviewer (me) drifted from it and silently shipped a broken diagram.Verdict comment that hit the trap: #898 (comment) (since patched to standalone form).
What
Adds one explicit Gotcha block under the OO / class diagram section. No code changes, no behavior changes -- this is persona-contract documentation that protects every future panel review's mermaid output.
Files
.apm/agents/python-architect.agent.md-- the authored source.github/agents/python-architect.agent.md-- regenerated viaapm install --target copilotper repo conventionapm.lock.yaml-- hash bump for the regenerated mirrorTest
The block reads as plain documentation; no executable contract changes. Verified by re-rendering the patched Epic #898 diagram on GitHub (now renders correctly with standalone
class X:::toucheddeclarations).Independent of and orthogonal to PR #897 (visual-communicator persona).